<?php

/**
 * 将经过JavaScript的utf8_to_b64函数编码的字符串解码为原始UTF-8字符串
 *
 * @param string $str 经过JavaScript utf8_to_b64函数编码后的Base64字符串
 * @return string 解码后的原始UTF-8字符串
 */
function b64_to_utf8($str) {
    // 1. 对Base64编码字符串进行解码，对应JavaScript中btoa()的逆操作
    // 将Base64格式还原为编码前的二进制数据（包含URI编码的转义序列）
    $decoded = base64_decode($str);

    // 2. 对解码后的内容进行URI解码，对应JavaScript中unescape()的逆操作
    // 将%XX形式的转义序列还原为原始UTF-8字符
    return rawurldecode($decoded);
}

/**
 * 将经过JavaScript的utf8_to_b64函数编码的字符串解码为原始UTF-8字符串
 *
 * @param string $str 经过JavaScript utf8_to_b64函数编码后的Base64字符串
 * @return string 解码后的原始UTF-8字符串
 * /
 * function b64_to_utf8($str) {
 * // 1. 对Base64编码字符串进行解码，对应JavaScript中btoa()的逆操作
 * // 将Base64格式还原为编码前的二进制数据（包含URI编码的转义序列）
 * $decoded = base64_decode($str);
 *
 * // 2. 对解码后的内容进行URI解码，对应JavaScript中unescape()的逆操作
 * // 将%XX形式的转义序列还原为原始UTF-8字符
 * return rawurldecode($decoded);
 * }/**
 * 将UTF-8编码的字符串转换为Base64编码，与JavaScript的utf8_to_b64函数功能一致
 *
 * 编码流程：
 * 1. 对UTF-8字符串进行URI组件编码（对应JavaScript的encodeURIComponent）
 * 2. 对URI编码结果进行解码（对应JavaScript的unescape）
 * 3. 将处理后的数据转换为Base64编码（对应JavaScript的btoa）
 *
 * @param string $str 要编码的UTF-8字符串
 * @return string 转换后的Base64编码字符串
 */
function utf8_to_b64($str) {
    // 1. 对字符串进行URI组件编码，类似JavaScript的encodeURIComponent
    // 会将特殊字符转换为%XX形式的十六进制转义序列
    $uri_encoded = rawurlencode($str);

    // 2. 对URI编码结果进行解码，类似JavaScript的unescape
    // 将%XX转义序列还原为对应的字符
    $unescaped = rawurldecode($uri_encoded);

    // 3. 将处理后的字符串转换为Base64编码，类似JavaScript的btoa
    return base64_encode($unescaped);
}

/**
 * 判断字符串是否为有效的Base64编码
 *
 * Base64编码具有特定的格式特征和可逆性，本函数通过多重验证确保准确性：
 * 1. 检查字符集是否仅包含Base64允许的字符
 * 2. 验证字符串长度是否为4的倍数
 * 3. 检查填充符'='的位置和数量是否符合规范
 * 4. 通过编码可逆性验证（解码后重新编码是否与原字符串一致）
 *
 * @param string $str 需要验证的字符串
 * @return bool 验证通过返回true，否则返回false
 */
function isBase64($str) {
    // 基础格式检查：
    // 正则表达式说明：
    // ^[a-zA-Z0-9\+\/]+  匹配开头的Base64有效字符（字母、数字、+、/）
    // (={0,2})$          匹配结尾0-2个填充符=，确保填充符只出现在末尾
    // 同时检查字符串长度是否为4的倍数（Base64编码的基本要求）
    if (!preg_match('/^[a-zA-Z0-9\+\/]+(={0,2})$/', $str) || strlen($str) % 4 !== 0) {
        return false;
    }

    // 严格模式解码（$strict=true）：
    // 遇到无效字符会返回false，而非默认模式下的忽略无效字符
    $decoded = base64_decode($str, true);

    // 双重验证：
    // 1. 解码必须成功（$decoded !== false）
    // 2. 解码后重新编码必须与原字符串完全一致（确保编码可逆性）
    return $decoded !== false && base64_encode($decoded) === $str;
}
